drafting where to work #768
Conversation
There was a problem hiding this comment.
Pull Request Overview
This pull request adds a new documentation page outlining guidelines for determining where to make contributions across various Elastic product areas.
- Introduces an overview of contribution pathways for content based on version (9.0+ vs. pre-9.0)
- Details product-specific sections for Kibana, Elasticsearch, Cloud, and Machine Learning
- Provides a mapping table for IA sections to product areas
docs/contribute/where-to-work.md
Outdated
|
|
||
| 1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code \+ low-level docs in the same PR. | ||
| 2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). As an example the [ES|QL overview](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the reference section of the docs [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) | ||
| 3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system |
There was a problem hiding this comment.
API reference docs live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system
If this content is going to persist as a public-facing document that we point all external and internal contributors to, I'm happy to beef up the "how to contribute to API docs" content here too.
docs/contribute/where-to-work.md
Outdated
|
|
||
| ### **Kibana** | ||
|
|
||
| #### **What has moved to elastic/docs-content?** |
There was a problem hiding this comment.
What has moved to elastic/docs-content?
IMO this feels like info that's only really relevant for internal contributors and overcomplicates things for external contributors. Is it worth splitting this content into separate sections aimed at external contributors (i.e. as simple as possible, open issue or click edit link) and internal contributors (i.e. where did the files I used to have go? how do I backport? etc)
There was a problem hiding this comment.
I kinda agree but I guess we have a lot of external contributors who will also be confused by the changes, so maybe it makes sense. Not sure!
georgewallace
force-pushed
the
where-to-work
branch
from
d4c00c3 to
2d9cf90
Compare
There was a problem hiding this comment.
I have some minor comments/suggestions. 🤓
Bigger picture, the page has multiple sections at the same level without clear visual separation. It kinda feels like a wall of text. Maybe add a few emojis or callouts for visual distinction.
I'd also reorder the sections a bit because it feels a little disjointed right now:
- Contribute to docs
- Where does the content live
- Mapping sections to product areas
- Report a bug
- Request an enhancement
- Work on docs-builder
This puts all the informational content together first, followed by all the action-oriented sections at the end.
Co-authored-by: Liam Thompson <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
| * For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) | ||
| * For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) |
There was a problem hiding this comment.
| * For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) | |
| * For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) | |
| * For **simple bug fixes and enhancements**, refer to [Contribute on the web](on-the-web.md) | |
| * For **complex or multi-page updates**, refer to our [legacy Building documentation guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) |
|
|
||
| * For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) | ||
| * For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) | ||
|
|
||
| ### Contribute to Elastic Stack version 9.0 docs and later | ||
| If you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/on-the-web#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. |
There was a problem hiding this comment.
consider putting this above the headings
|
|
||
| ### Contribute to Elastic Stack version 8.x docs and earlier | ||
| ### Contribute to version `8.x` docs and earlier |
There was a problem hiding this comment.
unfortunately, this is not just stack 8.x and 9.x. we need to consider ECE 3.x vs. 4.x, ECK 2.x vs. 3.x ...
I believe there is a resource floating around somewhere that has the version cutoffs in it (Brandon would be able to help with that). We should link to that, and possibly provide a quick reference for common products here.
stack is also an important word here that we need to preserve
| ### Contribute to version `9.0` docs and later | ||
|
|
||
| To contribute to `9.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](../syntax/index.md). | ||
| This content lives in one of three places: |
There was a problem hiding this comment.
| This content lives in one of three places: | |
| The source files for this content are hosted in one of three places: |
| To contribute to `9.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](../syntax/index.md). | ||
| This content lives in one of three places: | ||
|
|
||
| 1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code and low-level docs in the same PR. |
There was a problem hiding this comment.
| 1. **Reference/settings content** lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code and low-level docs in the same PR. | |
| 1. **Reference/settings content** is generally stored in markdown files in the relevant product repo. For example, the Elasticsearch configuration reference is stored in the [elastic/elasticsearch](https://github.com/elastic/elasticsearch/tree/main/docs) repo. This enables contributors to make updates that touch code and low-level docs in the same PR. |
|
|
||
| * For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) | ||
| * For **complex or multi-page updates** --> [Contribute locally](locally.md) | ||
|
|
||
| ## Where to find docs source files | ||
|
|
||
| Understand where your content of interest now sits in the new docs information architecture and the repos where source pages live. |
There was a problem hiding this comment.
I am concerned about having this list be so precise and simultaneously incomplete. we're covering 1/20 of the content
There was a problem hiding this comment.
I think we should focus on explaining the shape of the changes rather than explaining what in particular has moved where (closer to what you have below)
remember that redirects and mapping will help with this
| | **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | **Cloud:** Managing your cloud account | | ||
| | **Troubleshoot** | Content in this section is troubleshooting content for the different products as well as how to contact support. | All troubleshooting content | | ||
| | **Extend and contribute** | Content in this section focuses on contributing to Elastic products and building plugins, clients, and beats modules. | **Contributions guides for:** Kibana Logstash Beats <br>**Developer guides for:** Integrations Elasticsearch Plugins | | ||
| | **Reference** | Content in this section focuses on manuals for optional products as well as reference materials like query language references, configuration references, etc. | Reference content, Release notes, Developer guide | |
There was a problem hiding this comment.
missing: fleet, agent, logstash, clients, all totally housed in reference
| | **Solutions and use cases** | Content in this section focuses on the core solutions themselves and their user cases. | **Search:** core search solution content, playground, hybrid search <br>**Observability:** core observability content <br>**Security:** core security content | | ||
| | **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle <br>**Ingest:** ingesting data into Elasticsearch <br>**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | | ||
| | **Explore and analyze** | Content in this section focuses on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP) <br>**Machine Learning:** Anomaly detection, data frame analytics, NLP <br>**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. <br>**ResponseOps:** Alerts and Cases | | ||
| | **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management <br>**Cloud:** deploying and managing Elastic Cloud, Elastic Cloud Enterprise, Serverless, and ECK. | |
There was a problem hiding this comment.
this "cloud" grouping is imprecise - these were originally built from 3 repos already
| | **Manage data** | Content in this section focuses on learning about Elastic data store primitives, evaluating and implementing ingestion and data enrichment technologies, managing the lifecycle of your data and migrating data between clusters. | **Elasticsearch:** data store, migration, data lifecycle <br>**Ingest:** ingesting data into Elasticsearch <br>**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. | | ||
| | **Explore and analyze** | Content in this section focuses on querying, visualizing, and exploring data. Additionally it focusing on leveraging machine learning for data analysis and defining and responding to alerts | **Elasticsearch:** query languages, scripting, machine learning (NLP) <br>**Machine Learning:** Anomaly detection, data frame analytics, NLP <br>**Kibana**: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools. <br>**ResponseOps:** Alerts and Cases | | ||
| | **Deploy and manage** | Content in this section focuses on evaluating deployment options and setting your environment up. This section also contains content around managing, securing, and monitoring your cluster. | **Elasticsearch:** deploying elastic, production guidance, security, and Management <br>**Cloud:** deploying and managing Elastic Cloud, Elastic Cloud Enterprise, Serverless, and ECK. | | ||
| | **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | **Cloud:** Managing your cloud account | |
There was a problem hiding this comment.
| | **Manage your Cloud account** | Content in this section focuses specifically on managing Cloud accounts. | **Cloud:** Managing your cloud account | | |
| | **Manage your Cloud account** | Content in this section focuses specifically on managing Elastic Cloud accounts and certain user-level preferences. | **Cloud:** Managing your cloud account | |
|
|
||
| The following section shows a mapping of the different areas in the docs IA to the product areas and topics. | ||
|
|
||
| | **Area** | **Description** | **Sources (Area / Topic)** | |
There was a problem hiding this comment.
is "sources" intended to map old content to new content?
There was a problem hiding this comment.
consider seeing what you can pull out of here
No description provided.